SQL Server 2008: SQL Server Web Services - Building Web Services (part 1)

The first step is to decide which data or T-SQL functionality to expose to the clients who will ultimately call the web methods.

For this first example, you should create the stored procedure shown in Listing 1, which returns a row of data from the AdventureWorks2008 sample database. The purpose is to reveal a few attributes of an employee, given his or her unique EmployeeId.

Listing 1. A Stored Procedure for Your First Web Service

use AdventureWorks2008
GO
CREATE PROC dbo.GetEmployeeBasics
(
    @EmployeeId int
)
AS
SELECT
    e.BusinessEntityID,
    FirstName,
    LastName,
    e.JobTitle
FROM HumanResources.Employee e
JOIN Person.Person p ON
    e.BusinessEntityID = p. BusinessEntityID
WHERE BusinessEntityID = @EmployeeId

To expose this procedure as a web method of your web service, you use the CREATE ENDPOINT T-SQL statement, which falls under the formal SQL category of Data Definition Language (DDL). An endpoint can be defined as simply an entity on one end of a connection over a communication protocol, such as HTTP. SOAP endpoints have an additional nickname: nodes. SOAP nodes consist of a SOAP sender and a SOAP receiver, following the request-response model.

To create a SOAP-based HTTP endpoint, you use the fairly complex T-SQL syntax shown in Listing 2.

Listing 2. CREATE ENDPOINT T-SQL Syntax

CREATE ENDPOINT EndPointName [ AUTHORIZATION login ]
STATE = { STARTED | STOPPED | DISABLED }
AS HTTP
(
  PATH = 'url'
      , AUTHENTICATION =( { BASIC | DIGEST | INTEGRATED | NTLM | KERBEROS }
      [ ,...n ] )
      , PORTS = ( { CLEAR | SSL} [ ,... n ] )
  [ SITE = {'*' | '+' | 'webSite' },]
  [, CLEAR_PORT = clearPort ]
  [, SSL_PORT = SSLPort ]
  [, AUTH_REALM = { 'realm' | NONE } ]
  [, DEFAULT_LOGON_DOMAIN = { 'domain' | NONE } ]
  [, RESTRICT_IP = { NONE | ALL } ]
  [, COMPRESSION = { ENABLED | DISABLED } ]
  [, EXCEPT_IP = ( { <4-part-ip> | <4-part-ip>:<mask> } [ ,...n ] )
)
FOR SOAP
(
  [ { WEBMETHOD [ 'namespace' .] 'method_alias'
    (   NAME = 'database.owner.name'
      [ , SCHEMA = { NONE | STANDARD | DEFAULT } ]
      [ , FORMAT = { ALL_RESULTS | ROWSETS_ONLY } ]
    )
  } [ ,...n ] ]
  [   BATCHES = { ENABLED | DISABLED } ]
  [ , WSDL = { NONE | DEFAULT | 'sp_name' } ]
  [ , SESSIONS = { ENABLED | DISABLED } ]
  [ , LOGIN_TYPE = { MIXED | WINDOWS } ]
  [ , SESSION_TIMEOUT = timeoutInterval | NEVER ]
  [ , DATABASE = { 'database_name' | DEFAULT }
  [ , NAMESPACE = { 'namespace' | DEFAULT } ]
  [ , SCHEMA = { NONE | STANDARD } ]
  [ , CHARACTER_SET = { SQL | XML }]
  [ , MAX_SOAP_HEADERS_SIZE = { int | DEFAULT }]
)


					  

Before running the examples that follow, you should create a dedicated Windows login to use in the authorization scheme; this user should own and be able to access the database objects you create. In the examples that follow, this user is indicated as MyDomain\SQLWebServicesClient. Replace this name with your own.

Listing 3 contains the endpoint creation DDL that exposes dbo.GetEmployeeBasics to its web consumers.

Listing 3. T-SQL for Creating a SQL Server Web Service Endpoint

CREATE ENDPOINT EPT_SQL2008UnleashedExamples
AUTHORIZATION [MyDomain\SQLWebServicesClient]
STATE = STARTED
AS HTTP
(
    AUTHENTICATION = (INTEGRATED),
    PATH = '/opensql/',
    PORTS = (CLEAR, SSL),
    CLEAR_PORT = 80,
    SSL_PORT = 443,
    SITE = '*',
    COMPRESSION = ENABLED
)
FOR SOAP
(
    WEBMETHOD 'urn:www-samspublishing-com:examples'.'WM_GetEmployeeBasics'
    (
        NAME = 'AdventureWorks2008.dbo.GetEmployeeBasics',
        SCHEMA = STANDARD,
        FORMAT = ALL_RESULTS
    ),
    WSDL = DEFAULT,
    BATCHES = DISABLED,
    SCHEMA = STANDARD,
    LOGIN_TYPE = WINDOWS,
    SESSION_TIMEOUT = 120,
    DATABASE = 'AdventureWorks2008',
    NAMESPACE = 'urn:www-samspublishing-com:examples',
    CHARACTER_SET = XML
)


					  

In this listing, the name of the endpoint (EPT_SQL2008UnleashedExamples) immediately follows the keywords CREATE ENDPOINT.

The endpoint name is also conveniently used to drop the endpoint from the server, as follows:

DROP ENDPOINT EPT_SQL2008UnleashedExamples

But don’t drop the endpoint until you’ve finished trying out all the examples!

One caveat when creating endpoints: if the server name, port, and path you choose are already reserved or in use by another application (such as IIS) on your server, you may need to call the new stored procedure sp_reserve_http_namespace. This procedure explicitly reserves the URL of your choosing with http.sys so that you may use it for your endpoints. Here’s an example:

EXEC sp_reserve_http_namespace N'http://localhost:80/opensql'

Next in the DDL, the AUTHORIZATION keyword is used to specify the name of the login (either of authorization type Windows or SQL Server) that owns the endpoint. You can change the name of the login later by using the ALTER AUTHORIZATION statement, as in the following example:

ALTER AUTHORIZATION ON ENDPOINT::EPT_SQL2008UnleashedExamples
TO MyDomain\SomeOtherUser

Much as in Windows services, the possible states are STOPPED, STARTED, and DISABLED. (For security’s sake, STOPPED is the default.)

To change the state of any endpoint, you again invoke the ALTER ENDPOINT syntax. The following example stops the endpoint:

ALTER ENDPOINT EPT_SQL2008UnleashedExamples STATE = STOPPED

Again, don’t do this until you are done with the examples!